iperf3 v3.9 man page 中文译本

iperf3 - 测试网络吞吐性能。

iperf3 -s [ options ]

iperf3 -c server [ options ]

iperf3 是一个测试网络吞吐性能的工具。它能测试 TCP, UDP 或 SCTP 流量。要使用 iperf3 用户必须建立一个服务端和一个客户端。

iperf3 可执行文件包含了服务端和客户端的功能。iperf3 服务器可以通过 -s 或者 --server 选项启动，比如：

iperf3 -s

iperf3 --server

请注意，许多 iperf3 的配置选项都有短形式 (-s) 和长形式 (--server)。在这一节中，我们将普遍地使用短形式，除非这个配置只有长形式。

默认情况下，iperf3 服务端监听本机 5201 TCP 端口，使用此端口与客户端建立连接。可以使用 -p 选项自定义服务端监听的端口:

iperf3 -s -p 5002

在服务端进程启动后会等待从客户端 (以客户端模式运行的 iperf3 进程) 发来的连接请求。以客户端模式启动需要用 -c <host> 选项指定，其中 <host> 为客户端要连接到的服务端的地址， <host> 可以是 hostname, IPv4 文本或 IPv6 文本:

iperf3 -c iperf3.example.com
iperf3 -c 192.0.2.1
iperf3 -c 2001:db8::1

如果 iperf3 服务端在启动时指定了非默认的 TCP 端口，那么指定的端口号也需要在客户端启动时显式指定:

iperf3 -c iperf3.example.com -p 5002

服务端和客户端最初建立的 TCP 连接，用于交换测试参数、控制测试的启动和停止、传输测试结果。这个连接有时也被叫做 "control connection"。实际用于测试网络吞吐性能的数据通过单独的 TCP 连接传输；如果使用 UDP 协议测试吞吐性能，则有一个独立的 UDP 数据包流用于传输测试用的数据；如果使用 SCTP 协议测试吞吐性能，则会有独立的 SCTP 连接。具体协议取决于客户端指定的协议。

通常，测试数据会从客户端发往服务端，客户端会测量上行带宽。要测量客户端的下行带宽则可以在客户端启动时指定 -R 选项，即让服务端将测试数据发往客户端。

iperf3 -c iperf3.example.com -p 5202 -R

测试结果在服务端和客户端都会显示。结果同时显示在客户端和服务器上。每个测量间隔至少有一行输出 (默认情况下，测量间隔为 1 秒，但可以通过 -i 选项更改)。每行输出至少包括自测试开始以来的时间、间隔期间传输的数据量以及该间隔期间的平均速率。请注意，每个测量间隔输出的测试结果都是从打印输出的进程的角度计算的 (换句话说，客户端上打印的输出显示的是客户端测量出的数据)。 译者注: 客户端显示的是客户端发出数据的大小和速度等。服务端显示的是服务端收到的数据的大小和速度等。但传输过程中出现丢包和延迟的话，可能让服务端和客户端显示的速率不相等。

测试结束时会打印一组统计数据，尽可能多地显示发送方和接收方都看到的测试摘要，并给相应行打上标记。回想一下，默认情况下，客户端是发送方，服务器是接收方，尽管如上所述，使用 -R 选项将反转发送方和接收方。 译者注: 就是，客户端在执行完测试之后，打印一个客户端的测试摘要，再打印一个服务端的测试摘要。服务端只打印自己的测试摘要，不打印客户端的测试摘要。

通过指定 --get-server-output 选项，可以让客户端在打印完客户端要输出的数据之后，再打印服务端要输出的所有数据。

客户端或服务器都可以在启动时指定 -J 选项让测试结果以 JSON 格式输出，这在与其他程序集成时很有用。因为 JSON 结构的内容只有在测试完成后才能完全知道，所以在测试结束之前不会有 JSON 输出。

iperf3 有非常多的命令行选项可用于设置测试过程的细节。它们在下文 通用命令行选项 部分给出，并在 iperf3 的 help 输出中进行了总结，可以运行 iperf3 -h 查看。

-p, --port n

要监听 (客户端要连接) 的服务端端口号。必须在服务端和客户端指定相同的端口。默认端口为 5201。

-f, --format

[kmgtKMGT] 指定速率的显示格式: Kbits / Mbits / Gbits / Tbits / Kbytes / Mbytes / Gbytes / Tbytes。

-i, --interval n

两次吞吐量报告信息输出之间间隔 n 秒。默认值 1s。值 0 表示关闭输出。

-F, --file name

发送 (客户端，发送方) 或接收 (服务端，接收方) 文件，而不仅仅发送 (客户端，发送方) 随机数据或接收后将其丢弃 (服务端，接收方)。此功能用于确定存储子系统是否是文件传输的瓶颈。但 iperf3 不是可靠的文件传输工具。收到的文件的长度、属性以及某些情况下的内容可能与原文件不同。

-A, --affinity n/n,m

设置 CPU 绑定 (仅限 Linux, FreeBSD 和 Windows)。在客户端和服务器上，都可以使用此参数的 n 形式 (n 是 CPU 各个核心的编号) 将 iperf3 进程绑定在 CPU 的某个核心上。此外，在客户端，可以使用 n,m 形式的参数覆盖本次测试中服务端的 CPU 绑定。请注意，使用此功能时，进程将仅使用绑定到自身的单个 CPU 核心，而不是使用 CPU 的多个核心。

-B, --bind host

将 iPerf 进程绑定到与地址 host 关联的特定接口。 译者注: 就是绑定到机器上的某个网卡的接口上。对于客户端来说，这个选项可以指定数据包从哪个网卡接口流出。对于服务端来说，可以指定数据包从哪个网卡接口流入。

-V, --verbose

让输出更详细。

-J, --json

以 JSON 格式输出。

--logfile file

把输出写入到日志文件中。

--forceflush

每隔一段时间强制刷新 output。用于避免发送到管道输出被缓存。

--timestamps [format]

在每行输出的开头加上时间戳。默认情况下，时间戳的格式为 ctime(1) 输出的格式。或者，可以传递格式规范来定制时间戳，参见 strftime(3) 。

--d, --debug

输出调试信息。主要在开发 iPerf 的时候用。

-v, --version

显示版本信息，然后停止进程。

-h --help

显示帮助信息，然后停止进程。

-s, --server

以服务端模式启动程序。

-D, --daemon

在后台以守护进程的方式运行。

-I, --pidfile file

将进程 ID 写入到文件中，在程序以守护进程的形式运行时最有用。

-1, --one-off

处理一个客户端的连接之后就结束进程。

--server-bitrate-limit n[KMGT][/#]

在服务端设置限速。如果客户端指定的测试速率大于 n，或者从所有客户端流入数据的总速率大于 n，测试停止。默认值为 0，意味着没有限制。默认情况下，每 5s 计算一次这 5s 内流入数据的速率，这个时间间隔可以通过 / 后跟一个数字来指定。

--rsa-private-key-path file

用于解密客户端身份验证凭据的 RSA (不受密码保护的) 私钥路径 (如果编译的时候加入了 OpenSSL 支持的话)。

--authorized-users-path file

配置文件的路径，文件中包含了被允许执行 iperf 测试的用户的凭证 (如果编译的时候加入了 OpenSSL 支持的话)。该文件是以逗号分隔的用户名和密码哈希列表。有关文件结构的更多信息，请参见示例部分。

-c, --client host

以客户端模式启动，连接到指定的服务端。默认情况下，测试过程中客户端是数据发送方，服务端是数据接收方，使用 -R 选项可以让发送方和接收方角色互换。

--sctp

使用 SCTP 而不是 TCP (只能在 FreeBSD 和 Linux 上用)。

-u, --udp

使用 UDP 而不是 TCP。

--connect-timeout n

设置客户端发起到服务端的 control connection 的超时时间，单位是 ms。默认的值是系统中 TCP 连接的超时时间。将其调小一些可能会加速检测 iperf3 服务端掉线情况。

译者注: control connection 是服务端和客户端连接后的第一个连接，这是个 TCP 连接，用于交换测试参数，控制测试的启动和停止，传输测试结果。

-b, --bitrate n[KMGT][/#]

设定一个目标为 n bits/sec 的速率限制 (默认情况下，UDP 有 1 Mbit/sec 的发送速率限制，TCP / SCTP 无发送速率限制)。如果有多个输入 / 输出流 (-P 选项)，限速会被否下应用到所有的流 (译者注: m 个限速为 n 的流，速度上限是 m*n。) 。可以在之后加上 / 然后跟一个数字来调用 burst mode 。它将不间断地发送给定数量的数据包，即使传输速率暂时超过了指定的吞吐量限制 (译者注: 即使速度超过了限速还是一直传输数据直到占满带宽) 。将目标限速设为 0 将禁用限速 (对于 UDP 测试特别有用)。该吞吐量限制在 iperf3 内部实现，可用于所有平台。与 --fq-rate 标志进行比较。此选项用于替换 --bandwidth 选项 (该选项现在已被弃用，但仍有效)。 译者注: 简单理解，这个选项设置了一个 pacing 速率 (一个限速)。前面一句话需要结合 --fq-rate 配置项理解。

--pacing-timer n[KMGT]

以毫秒为单位设置每次检查发送的数据量，默认值是 1000ms，也就是 1s。这个选项控制 iperf3 中 -b / --bitrate 选项的 pacing timer。计时器按此参数设置的间隔触发。pacing timer参数的较小值可以平滑 iperf3 发出的流量，但由于更频繁的计时器处理，可能会以性能为代价。

译者注: 这个选项主要的作用是，尽量减少发送数据间等待的时间。假设带宽 100M，限速 10M，pacing timer 是 1s，机器在 1s 中可以发送 100M 数据出去。有了限速之后 1s 只能发 10M 出去，那么机器会在 1s 开头的 100ms 把数据发完，剩下 900ms 什么都不干。这时候调小 pacing timer 为 1ms，那么每隔 1ms iperf3 都会检查数据发送情况，这时候可能每 1ms 都有 0.1M 数据被发出。

--fq-rate n[KMGT]

设置用于基于 fair-queueing 的 socket 级别的 pacing 速率，以 bit/s 为单位。这个 pacing 是对其他 pacing 的补充，比如 -b / --bitrate ，并且它们可以同时用在同一个测试中。仅在支持 SO_MAX_PACING_RATE 这个 socket 选项的平台上可用 (当前仅限 Linux)。默认情况下，不开启基于 fair-queueing 的 pacing。

译者注: 简单理解，这个选项也设置了一个 pacing 速率 (一个限速)，只不过优先级很低。--fq-rate 和 --bitrate 同时出现但取值不同时，速率限制为较小的那个，并且开启基于 fair-queueing 的 pacing。

--no-fq-socket-pacing

这个选项已经启用并将被移除。它的效果和 --fq-rate=0 相同。

-t, --time n

测试持续的时间，单位是秒。默认 10s。

-n, --bytes n[KMGT]

要传输的数据量。(是 -t 选项的替代选项)

-k, --blockcount n[KMGT]

要传输的数据包的数量。(是 -t 或 -n 选项的替代选项)

-l, --length n[KMGT]

要读取或写入的缓冲区的长度。对于 TCP 测试来说，默认值是 128KB。对于 UDP 测试来说，iperf3 会尝试根据路线上的 MTU 动态地确定一个合理的被发出的数据包的大小，如果无法确定则使用 1460 bytes 作为数据包大小。对于 SCTP 测试来说，默认值是 64KB。

--cport port

将数据流绑定到一个特定的客户端端口上。(仅限 TCP 和 UDP，默认使用随机端口) 译者注: 客户端默认使用随机端口来收发数据。这个选项可以用来指定收发数据的端口。

-P, --parallel n

指定要启动几个客户端数据流。请注意，iperf3 是单线程程序，因此，如果使用了 CPU 绑定，将不会产生更高的吞吐量。 译者注: 启动几个数据流就是启动几个线程，但如果使用 --affinity 绑定了 CPU 小核的话，不管开几个线程，能用的小核就那一个，也就没有什么性能提升了。但是这个选项在一个线程没法占满整个带宽的时候很有用。

-R, --reverse

默认情况下，客户端传输数据到服务端。这个选项可以让服务端传输数据到客户端。

--bidir

测试同时、双向的网络吞吐，客户端和服务器同时发送和接收数据。

-w, --windows n[KMGT]

设置 window size 或者 socket buffer size，这个设置也将发送到服务端，并在服务端使用同样的配置。

-M, --set-mss n

设置 TCP/SCTP mss (最大片段大小) (值为 MTU - 40 bytes)。

译者注: 主机的 MSS 的值是链路层的 MTU 减去 40 个字节 (IP 标头和 TCP 标头各 20 字节，总共为 40 字节)，这时 MSS 的值为 1460。有时候还要再减去时间戳要占用的 12 字节，这时 MSS 的值为 1448。

-N, --no-delay

取消 TCP/STCP 的延迟 (set TCP/STCP no delay)，关闭 Nagle 的算法。

-4, --version4

只使用 IPv4 地址。

-6, --version6

只是用 IPv6 地址。

-S, --tos n

设置 IP 服务类型。可以使用八进制和十六进制的常用前缀，即 52, 064 和 0x34 是相同的值。 译者注: 详细请查看 IP 协议的 TOS 字段。

--dscp dscp

设置 IP DSCP 位。接受数字和符号值。数值可以用十进制、八进制和十六进制指定 (格式参见 --tos)。 译者注: 详细请查看 IP 协议的 DSCP 部分。

-L, --flowlabel n

设置 IPv6 flow label。目前只支持 Linux。

-X, --xbind name

使用 sctp_bindx(3) 将 SCTP 关联绑定到特定的链接子集。如果指定了此选项，就忽略 --B 选项。通常，在建立关联时，SCTP 将包含本地主机上所有活动连接的协议地址。指定至少一个 -X 将禁用此行为。必须为要包含在关联中的每个链接指定此选项，并且 iperf 服务器和客户端都支持此选项 (客户端通过将第一个 -X 传递给 bind(2) 来支持)。主机名可以作为选项的值，并使用 getaddrinfo(3) 进行解析。如果指定了 -4 或 -6 选项，则不被解析为指定协议族内的地址的 name 值将被忽略。

-nstreams n

设定 SCTP 流的数量。

-Z, --zerocopy

使用 "zero copy" 来发送数据，比如 sendfile(2) ，而不使用 write(2) 。

-O, --omit n

省略测试的前 n 秒，跳过TCP慢速启动周期。

-T, --title str

在每一行输出之前加上这个字符串。

--extra-data str

指定一个字符串，将其包含在 JSON 输出中。

-C, --congestion algo

设置拥塞控制算法 (仅限 Linux 和 FreeBSD)。旧 --linux-congestion 选项和此选项效果相同，虽然可以使用，但已被废弃。

--get-server-output

从服务端获取输出。输出格式由服务端决定 (特别是，如果使用 --json 选项启动服务器，则输出将采用 json 格式，否则采用人类可读的格式)。如果客户端使用 --json 选项启动，则服务器输出包含在客户端输出的 json 对象中；否则，服务端的输出将在人类可读的客户端输出的后面被输出。

--udp-counters-64bit

在 UDP 测试的数据包中使用 64 位计数器。使用该配置有助于在长时间或高比特率 UDP 测试期间防止计数器溢出。客户端和服务器都需要至少运行 3.1 版，此选项才能工作。在将来的某个时候，它可能会成为默认行为。

--repeating-payload

在负载中使用重复模式，而不是随机字节。iperf2 也使用了相同的负载模式 (ASCII 字符 0 - 9 按顺序不断重复发送)。这可能有助于测试和展现带硬件压缩功能的网络设备 (包括一些 WiFi 接入点) 中的问题，其中 iperf2 和 iperf3 的性能不同，只是基于负载熵。重新创建可能受有效负载熵（例如，压缩）影响的结果。

译者注: 李守中用 tcpdump 抓了一下使用这个配置项启动的客户端发出去的包 (iperf2 和 iperf3 都抓了)。在 wireshark 里看到，发到服务端的测试数据都是 0-9 的这 10 个数字，而且是 (01234556789){n} 这样式的。要理解第二句，得理解熵 (用于形容系统中的无序程度，熵值越高系统越无序) 的概念，媒体文件熵值高，文本文件熵值低。第二句意思是说，可以使用降低要传输的数据的熵值的方式 (就是让发出去的数据尽量有序) 来测试网络设备的功能是否正常。比如网络设备上硬件级别的数据压缩功能，数据有序程度和压缩效果成正比。先用熵值高的媒体文件测一下，再用熵值低的有序数据测一下，根据压缩效果可以判断硬件有没有问题。

--username username

用于服务端身份验证的用户名 (如果编译时候加入了 OpenSSL 支持的话)。在执行命令的时候会有交互式的密码输入提示。请注意，密码也可以通过环境变量 IPERF3_PASSWORD 来指定。如果有这个环境变量，将不会有交互式密码输入提示。

--rsa-public-key-path file

用于加密加密身份验证凭据的 RSA 公钥文件的路径。(如果编译时候加入了 OpenSSL 支持的话)

openssl genrsa -des3 -out private.pem 2048
openssl rsa -in private.pem -outform PEM -pubout -out public.pem
openssl rsa -in private.pem -out private_not_protected.pem -outform PEM

S_USER=mario S_PASSWD=rossi
echo -n "{$S_USER}$S_PASSWD" | sha256sum | awk '{ print $1 }'

> cat credentials.csv
# file format: username,sha256
mario,bf7a49a846d44b454a5d11e7acfaf13d138bbe0b7483aa3e050879700572709b

iperf3 的贡献者列表可在以下文档中找到：https://software.es.net/iperf/dev.html#authors.

libiperf(3), https://software.es.net/iperf